<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.5.2" />
<title>Gerrit Code Review - Access Controls</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #dddddd;
  color: #777777;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > div.content {
  white-space: pre;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}


@media print {
  div#footer-badges { display: none; }
}

div#toc {
  margin-bottom: 2.5em;
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock-content {
  white-space: pre;
}
div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
}

div.exampleblock-content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      // Use [\s\S] in place of . so multi-line matches work.
      // Because JavaScript has no s (dotall) regex flag.
      note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      spans[i].innerHTML =
        "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
        "' title='View footnote' class='footnote'>" + n + "</a>]";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
}

}
/*]]>*/
</script>
</head>
<body>
<div id="header">
<h1>Gerrit Code Review - Access Controls</h1>
<span id="revnumber">version 2.3</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>Access controls in Gerrit are group based.  Every user account is a
member of one or more groups, and access and privileges are granted
to those groups.  Access rights cannot be granted to individual
users.</p></div>
</div>
</div>
<h2 id="_system_groups">System Groups</h2>
<div class="sectionbody">
<div class="paragraph"><p>Gerrit comes with 4 system groups, with special access privileges
and membership management.  The identity of these groups is set
in the <tt>system_config</tt> table within the database, so the groups
can be renamed after installation if desired.</p></div>
<h3 id="administrators">Administrators</h3><div style="clear:left"></div>
<div class="paragraph"><p>This is the Gerrit "root" identity.</p></div>
<div class="paragraph"><p>Users in the <em>Administrators</em> group can perform any action under
the Admin menu, to any group or project, without further validation
of any other access controls.  In most installations only those
users who have direct filesystem and database access would be
placed into this group.</p></div>
<div class="paragraph"><p>Membership in the <em>Administrators</em> group does not imply any other
access rights.  Administrators do not automatically get code review
approval or submit rights in projects.  This is a feature designed
to permit administrative users to otherwise access Gerrit as any
other normal user would, without needing two different accounts.</p></div>
<h3 id="anonymous_users">Anonymous Users</h3><div style="clear:left"></div>
<div class="paragraph"><p>All users are automatically a member of this group.  Users who are
not signed in are a member of only this group, and no others.</p></div>
<div class="paragraph"><p>Any access rights assigned to this group are inherited by all users.</p></div>
<div class="paragraph"><p>Administrators and project owners can grant access rights to this
group in order to permit anonymous users to view project changes,
without requiring sign in first.  Currently it is only worthwhile
to grant <tt>Read</tt> access to this group as Gerrit requires an account
identity for all other operations.</p></div>
<h3 id="non-interactive_users">Non-Interactive Users</h3><div style="clear:left"></div>
<div class="paragraph"><p>This is an internal user group, members of this group are not expected
to perform interactive operations on the Gerrit web frontend.</p></div>
<div class="paragraph"><p>However, sometimes such a user may need a separate thread pool in
order to prevent it from grabbing threads from the interactive users.</p></div>
<div class="paragraph"><p>These users live in a second thread pool, which separates operations
made by the non-interactive users from the ones made by the interactive
users. This ensures that the interactive users can keep working when
resources are tight.</p></div>
<h3 id="project_owners">Project Owners</h3><div style="clear:left"></div>
<div class="paragraph"><p>Access rights assigned to this group are always evaluated within the
context of a project to which the access rights apply. These rights
therefore apply to all the users who are owners of this project.</p></div>
<div class="paragraph"><p>By assigning access rights to this group on a parent project Gerrit
administrators can define a set of default access rights for
<a href="#category_owner">project owners</a>. Child projects inherit these
access rights where they are resolved to the users that own the child
project.  Having default access rights for
<a href="#category_owner">project owners</a> assigned on a parent project may
avoid the need to initially configure access rights for
newly created child projects.</p></div>
<h3 id="registered_users">Registered Users</h3><div style="clear:left"></div>
<div class="paragraph"><p>All signed-in users are automatically a member of this group (and
also <a href="#anonymous_users"><em>Anonymous Users</em></a>, see above).</p></div>
<div class="paragraph"><p>Any access rights assigned to this group are inherited by all
users as soon as they sign-in to Gerrit.  If OpenID authentication
is being employed, moving from only <em>Anonymous Users</em> into this
group is very easy.  Caution should be taken when assigning any
permissions to this group.</p></div>
<div class="paragraph"><p>It is typical to assign <tt>Code Review -1..+1</tt> to this group,
allowing signed-in users to vote on a change, but not actually
cause it to become approved or rejected.</p></div>
<div class="paragraph"><p>Registered users are always permitted to make and publish comments
on any change in any project they have <tt>Read</tt> access to.</p></div>
</div>
<h2 id="_account_groups">Account Groups</h2>
<div class="sectionbody">
<div class="paragraph"><p>Account groups contain a list of zero or more user account members,
added individually by a group owner.  Any user account listed as
a group member is given any access rights granted to the group.</p></div>
<div class="paragraph"><p>Every group has one other group designated as its owner.  Users who
are members of the owner group can:</p></div>
<div class="ulist"><ul>
<li>
<p>
Add users and other groups to this group
</p>
</li>
<li>
<p>
Remove users and other groups from this group
</p>
</li>
<li>
<p>
Change the name of this group
</p>
</li>
<li>
<p>
Change the description of this group
</p>
</li>
<li>
<p>
Change the owner of this group, to another group
</p>
</li>
</ul></div>
<div class="paragraph"><p>It is permissible for a group to own itself, allowing the group
members to directly manage who their peers are.</p></div>
<div class="paragraph"><p>Newly created groups are automatically created as owning themselves,
with the creating user as the only member.  This permits the group
creator to add additional members, and change the owner to another
group if desired.</p></div>
<div class="paragraph"><p>It is somewhat common to create two groups at the same time,
for example <tt>Foo</tt> and <tt>Foo-admin</tt>, where the latter group
<tt>Foo-admin</tt> owns both itself and also group <tt>Foo</tt>.  Users who
are members of <tt>Foo-admin</tt> can thus control the membership of
<tt>Foo</tt>, without actually having the access rights granted to <tt>Foo</tt>.
This configuration can help prevent accidental submits when the
members of <tt>Foo</tt> have submit rights on a project, and the members of
<tt>Foo-admin</tt> typically do not need to have such rights.</p></div>
</div>
<h2 id="_project_access_control_lists">Project Access Control Lists</h2>
<div class="sectionbody">
<div class="paragraph"><p>A system wide access control list affecting all projects is stored in
project "<tt>All-Projects</tt>".  This inheritance can be configured
through <a href="cmd-set-project-parent.html">gerrit set-project-parent</a>.</p></div>
<div class="paragraph"><p>Per-project access control lists are also supported.</p></div>
<div class="paragraph"><p>Users are permitted to use the maximum range granted to any of their
groups in an approval category.  For example, a user is a member of
<tt>Foo Leads</tt>, and the following ACLs are granted on a project:</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
<thead>
<tr>
<th align="left" valign="top">Group           </th>
<th align="left" valign="top">Reference Name </th>
<th align="left" valign="top">Category</th>
<th align="left" valign="top">Range</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Anonymous Users</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-1..+1</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Registered Users</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-1..+2</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Foo Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..0</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>Then the effective range permitted to be used by the user is
<tt>-2..+2</tt>, as the user is a member of all three groups (see above
about the system groups) and the maximum range is chosen (so the
lowest value granted to any group, and the highest value granted
to any group).</p></div>
<div class="paragraph"><p>Reference-level access control is also possible.</p></div>
<div class="paragraph"><p>Permissions can be set on a single reference name to match one
branch (e.g. <tt>refs/heads/master</tt>), or on a reference namespace
(e.g. <tt>refs/heads/*</tt>) to match any branch starting with that
prefix. So a permission with <tt>refs/heads/*</tt> will match
<tt>refs/heads/master</tt> and <tt>refs/heads/experimental</tt>, etc.</p></div>
<div class="paragraph"><p>Reference names can also be described with a regular expression
by prefixing the reference name with <tt>^</tt>.  For example
<tt>^refs/heads/[a-z]{1,8}</tt> matches all lower case branch names
between 1 and 8 characters long.  Within a regular expression <tt>.</tt>
is a wildcard matching any character, but may be escaped as <tt>\.</tt>.
The <a href="http://www.brics.dk/automaton/">dk.brics.automaton library</a>
is used for evaluation of regular expression access control
rules. See the library documentation for details on this
particular regular expression flavor.</p></div>
<div class="paragraph"><p>References can have the current user name automatically included,
creating dynamic access controls that change to match the currently
logged in user.  For example to provide a personal sandbox space
to all developers, <tt>refs/heads/sandbox/${username}/*</tt> allowing
the user <em>joe</em> to use <em>refs/heads/sandbox/joe/foo</em>.</p></div>
<div class="paragraph"><p>When evaluating a reference-level access right, Gerrit will use
the full set of access rights to determine if the user
is allowed to perform a given action. For example, if a user is a
member of <tt>Foo Leads</tt>, they are reviewing a change destined for
the <tt>refs/heads/qa</tt> branch, and the following ACLs are granted
on the project:</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<thead>
<tr>
<th align="left" valign="top">Group            </th>
<th align="left" valign="top">Reference Name</th>
<th align="left" valign="top">Category   </th>
<th align="left" valign="top">Range   </th>
<th align="left" valign="top">Exclusive</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Registered Users</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-1..+1</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Foo Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">QA Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/qa</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>Then the effective range permitted to be used by the user is
<tt>-2..+2</tt>, as the user&#8217;s membership of <tt>Foo Leads</tt> effectively grant
them access to the entire reference space, thanks to the wildcard.</p></div>
<div class="paragraph"><p>Gerrit also supports exclusive reference-level access control.</p></div>
<div class="paragraph"><p>It is possible to configure Gerrit to grant an exclusive ref level
access control so that only users of a specific group can perform
an operation on a project/reference pair. This is done by ticking
the exclusive flag when setting the permission for the
<tt>refs/heads/qa</tt> branch.</p></div>
<div class="paragraph"><p>For example, if a user who is a member of <tt>Foo Leads</tt> tries to
review a change destined for branch <tt>refs/heads/qa</tt> in a project,
and the following ACLs are granted:</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<thead>
<tr>
<th align="left" valign="top">Group           </th>
<th align="left" valign="top">Reference Name</th>
<th align="left" valign="top">Category   </th>
<th align="left" valign="top">Range   </th>
<th align="left" valign="top">Exclusive</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Registered Users</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-1..+1</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Foo Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">QA Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/qa</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table">X</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>Then this user will not have <tt>Code Review</tt> rights on that change,
since there is an exclusive access right in place for the
<tt>refs/heads/qa</tt> branch. This allows locking down access for a
particular branch to a limited set of users, bypassing inherited
rights and wildcards.</p></div>
<div class="paragraph"><p>In order to grant the ability to <tt>Code Review</tt> to the members of
<tt>Foo Leads</tt>, in <tt>refs/heads/qa</tt> then the following access rights
would be needed:</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<col width="20%" />
<thead>
<tr>
<th align="left" valign="top">Group           </th>
<th align="left" valign="top">Reference Name</th>
<th align="left" valign="top">Category   </th>
<th align="left" valign="top">Range   </th>
<th align="left" valign="top">Exclusive</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Registered Users</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-1..+1</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Foo Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/*</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">QA Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/qa</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table">X</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Foo Leads</p></td>
<td align="left" valign="top"><p class="table">refs/heads/qa</p></td>
<td align="left" valign="top"><p class="table">Code Review</p></td>
<td align="left" valign="top"><p class="table">-2..+2</p></td>
<td align="left" valign="top"><p class="table"></p></td>
</tr>
</tbody>
</table>
</div>
<h3 id="_openid_authentication">OpenID Authentication</h3><div style="clear:left"></div>
<div class="paragraph"><p>If the Gerrit instance is configured to use OpenID authentication,
an account&#8217;s effective group membership will be restricted to only
the <tt>Anonymous Users</tt> and <tt>Registered Users</tt> groups, unless <strong>all</strong>
of its OpenID identities match one or more of the patterns listed
in the <tt>auth.trustedOpenID</tt> list from <tt>gerrit.config</tt>.</p></div>
<h3 id="_all_projects">All Projects</h3><div style="clear:left"></div>
<div class="paragraph"><p>Any access right granted to a group within <tt>All-Projects</tt>
is automatically inherited by every other project in the same
Gerrit instance.  These rights can be seen, but not modified,
in any other project&#8217;s <tt>Access</tt> administration tab.</p></div>
<div class="paragraph"><p>Only members of the groups with the <tt>Administrate Server</tt> capability
may edit the access control list for <tt>All-Projects</tt>. By default this
capability is given to the group <tt>Administrators</tt>, but can be given
to more groups.</p></div>
<div class="paragraph"><p>Ownership of this project cannot be delegated to another group.
This restriction is by design.  Granting ownership to another
group gives nearly the same level of access as membership in
<tt>Administrators</tt> does, as group members would be able to alter
permissions for every managed project including global capabilities.</p></div>
<h3 id="_per_project">Per-Project</h3><div style="clear:left"></div>
<div class="paragraph"><p>The per-project ACL is evaluated before the global <tt>All-Projects</tt> ACL,
permitting some limited override capability to project owners. This
behavior is generally only useful on the <tt>Read</tt> category when
granting <em>DENY</em> within a specific project to deny a group access.</p></div>
</div>
<h2 id="access_category">Access Categories</h2>
<div class="sectionbody">
<div class="paragraph"><p>Gerrit comes pre-configured with several default categories that
can be granted to groups within projects, enabling functionality
for that group&#8217;s members.</p></div>
<div class="paragraph"><p>With the release of the Gerrit 2.2.x series, the web GUI for ACL
configuration was rewritten from scratch.  Use this
<a href="#conversion_table">table</a> to better understand the access rights
conversions from the Gerrit 2.1.x to the Gerrit 2.2.x series.</p></div>
<h3 id="category_label-Verified">Label: Verified</h3><div style="clear:left"></div>
<div class="paragraph"><p>The verified category is one of two default categories that is
configured upon the creation of a Gerrit instance. It may have
any meaning the project desires.  It was originally invented by
the Android Open Source Project to mean
<em>compiles, passes basic unit tests</em>.</p></div>
<div class="paragraph"><p>The range of values is:</p></div>
<div class="ulist"><ul>
<li>
<p>
-1 Fails
</p>
<div class="paragraph"><p>Tried to compile, but got a compile error, or tried to run tests,
but one or more tests did not pass.  This value is valid
across all patch sets in the same change, i.e. the reviewer must
actively change his/her review to something else before the change
is submittable.</p></div>
<div class="paragraph"><p><strong>Any -1 blocks submit.</strong></p></div>
</li>
<li>
<p>
0 No score
</p>
<div class="paragraph"><p>Didn&#8217;t try to perform the verification tasks.</p></div>
</li>
<li>
<p>
+1 Verified
</p>
<div class="paragraph"><p>Compiled (and ran tests) successfully.</p></div>
<div class="paragraph"><p><strong>Any +1 enables submit.</strong></p></div>
</li>
</ul></div>
<div class="paragraph"><p>For a change to be submittable, the change must have a <tt>+1 Verified</tt>
in this category from at least one authorized user, and no <tt>-1 Fails</tt>
from an authorized user.  Thus, <tt>-1 Fails</tt> can block a submit,
while <tt>+1 Verified</tt> enables a submit.</p></div>
<div class="paragraph"><p>If a Gerrit installation does not wish to use this category in any
project, it can be deleted from the database:</p></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="literalblock">
<div class="content">
<pre><tt>DELETE FROM approval_categories      WHERE category_id = 'VRIF';
DELETE FROM approval_category_values WHERE category_id = 'VRIF';</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>If a Gerrit installation wants to modify the description text
associated with these category values, the text can be updated
in the <tt>name</tt> column of the <tt>category_id = 'VRIF'</tt> rows in the
<tt>approval_category_values</tt> table.</p></div>
<div class="paragraph"><p>Additional values could also be added to this category, to allow it
to behave more like <tt>Code Review</tt> (below).  Insert -2 and +2 value
rows into the <tt>approval_category_values</tt> with <tt>category_id</tt> set to
<tt>VRIF</tt> to get the same behavior.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">A restart is required after making database changes.
See <a href="#restart_changes">below</a>.</td>
</tr></table>
</div>
<h3 id="category_label-Code-Review">Label: Code Review</h3><div style="clear:left"></div>
<div class="paragraph"><p>The code review category is the second of two default categories that
is configured upon the creation of a Gerrit instance. It may have
any meaning the project desires.  It was originally invented by the
Android Open Source Project to mean <em>I read the code and it seems
reasonably correct</em>.</p></div>
<div class="paragraph"><p>The range of values is:</p></div>
<div class="ulist"><ul>
<li>
<p>
-2 Do not submit
</p>
<div class="paragraph"><p>The code is so horribly incorrect/buggy/broken that it must not be
submitted to this project, or to this branch.  This value is valid
across all patch sets in the same change, i.e. the reviewer must
actively change his/her review to something else before the change
is submittable.</p></div>
<div class="paragraph"><p><strong>Any -2 blocks submit.</strong></p></div>
</li>
<li>
<p>
-1 I would prefer that you didn&#8217;t submit this
</p>
<div class="paragraph"><p>The code doesn&#8217;t look right, or could be done differently, but
the reviewer is willing to live with it as-is if another reviewer
accepts it, perhaps because it is better than what is currently in
the project.  Often this is also used by contributors who don&#8217;t like
the change, but also aren&#8217;t responsible for the project long-term
and thus don&#8217;t have final say on change submission.</p></div>
<div class="paragraph"><p>Does not block submit.</p></div>
</li>
<li>
<p>
0 No score
</p>
<div class="paragraph"><p>Didn&#8217;t try to perform the code review task, or glanced over it but
don&#8217;t have an informed opinion yet.</p></div>
</li>
<li>
<p>
+1 Looks good to me, but someone else must approve
</p>
<div class="paragraph"><p>The code looks right to this reviewer, but the reviewer doesn&#8217;t
have access to the <tt>+2</tt> value for this category.  Often this is
used by contributors to a project who were able to review the change
and like what it is doing, but don&#8217;t have final approval over what
gets submitted.</p></div>
</li>
<li>
<p>
+2 Looks good to me, approved
</p>
<div class="paragraph"><p>Basically the same as <tt>+1</tt>, but for those who have final say over
how the project will develop.</p></div>
<div class="paragraph"><p><strong>Any +2 enables submit.</strong></p></div>
</li>
</ul></div>
<div class="paragraph"><p>For a change to be submittable, the latest patch set must have a
<tt>+2 Looks good to me, approved</tt> in this category from at least one
authorized user, and no <tt>-2 Do not submit</tt> from an authorized user.
Thus <tt>-2</tt> on any patch set can block a submit, while <tt>+2</tt> on the
latest patch set can enable it.</p></div>
<div class="paragraph"><p>If a Gerrit installation does not wish to use this category in any
project, it can be deleted from the database:</p></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="literalblock">
<div class="content">
<pre><tt>DELETE FROM approval_categories      WHERE category_id = 'CRVW';
DELETE FROM approval_category_values WHERE category_id = 'CRVW';</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>If a Gerrit installation wants to modify the description text
associated with these category values, the text can be updated
in the <tt>name</tt> column of the <tt>category_id = 'CRVW'</tt> rows in the
<tt>approval_category_values</tt> table.</p></div>
<div class="paragraph"><p>Additional values could be inserted into <tt>approval_category_values</tt>
to further extend the negative and positive range, but there is
likely little value in doing so as this only expands the middle
region.  This category is a <tt>MaxWithBlock</tt> type, which means that
the lowest negative value if present blocks a submit, while the
highest positive value is required to enable submit.</p></div>
<div class="paragraph" id="function_MaxNoBlock"><p>There is also a <tt>MaxNoBlock</tt> category which still requires the
highest positive value to submit, but the lowest negative value will
not block the change, and does not carry over between patch sets.
This level is mostly useful for automated code-reviews that may
have false-negatives that shouldn&#8217;t block the change.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">A restart is required after making database changes.
See <a href="#restart_changes">below</a>.</td>
</tr></table>
</div>
<h3 id="category_create">Create reference</h3><div style="clear:left"></div>
<div class="paragraph"><p>The create reference category controls whether it is possible to
create new references, branches or tags.  This implies that the
reference must not already exist, it&#8217;s not a destructive permission
in that you can&#8217;t overwrite or remove any previosuly existing
references (and also discard any commits in the process).</p></div>
<div class="paragraph"><p>It&#8217;s probably most common to either permit the creation of a single
branch in many gits (by granting permission on a parent project), or
to grant this permission to a name pattern of branches.</p></div>
<div class="paragraph"><p>This permission is often given in conjunction with regular push
branch permissions, allowing the holder of both to create new branches
as well as bypass review for new commits on that branch.</p></div>
<div class="paragraph"><p>To push lightweight (non annotated) tags, grant
<tt>Create Reference</tt> for reference name <tt>refs/tags/*</tt>, as lightweight
tags are implemented just like branches in Git.</p></div>
<div class="paragraph"><p>For example, to grant the possibility to create new branches under the
namespace <tt>foo</tt>, you have to grant this permission on
<tt>refs/heads/foo/*</tt> for the group that should have it.
Finally, if you plan to grant each user a personal namespace in
where they are free to create as many branches as they wish, you
should grant the create reference permission so it&#8217;s possible
to create new branches. This is done by using the special
<tt>${username}</tt> keyword in the reference pattern, e.g.
<tt>refs/heads/sandbox/${username}/*</tt>. If you do, it&#8217;s also recommended
you grant the users the push force permission to be able to clean up
stale branches.</p></div>
<h3 id="category_forge_author">Forge Author</h3><div style="clear:left"></div>
<div class="paragraph"><p>Normally Gerrit requires the author and the committer identity
lines in a Git commit object (or tagger line in an annotated tag) to
match one of the registered email addresses of the uploading user.
This permission allows users to bypass parts of that validation, which
may be necessary when mirroring changes from an upstream project.</p></div>
<div class="paragraph"><p>Permits the use of an unverified author line in commit objects.
This can be useful when applying patches received by email from
3rd parties, when cherry-picking changes written by others across
branches, or when amending someone else&#8217;s commit to fix up a minor
problem before submitting.</p></div>
<div class="paragraph"><p>By default this is granted to <tt>Registered Users</tt> in all projects,
but a site administrator may disable it if verified authorship
is required.</p></div>
<h3 id="category_forge_committer">Forge Committer</h3><div style="clear:left"></div>
<div class="paragraph"><p>Normally Gerrit requires the author and the committer identity
lines in a Git commit object (or tagger line in an annotated tag) to
match one of the registered email addresses of the uploading user.
This permission allows users to bypass parts of that validation, which
may be necessary when mirroring changes from an upstream project.</p></div>
<div class="paragraph"><p>Allows the use of an unverified committer line in commit objects, or an
unverified tagger line in annotated tag objects.  Typically this is only
required when mirroring commits from an upstream project repository.</p></div>
<h3 id="category_forge_server">Forge Server</h3><div style="clear:left"></div>
<div class="paragraph"><p>Normally Gerrit requires the author and the committer identity
lines in a Git commit object (or tagger line in an annotated tag) to
match one of the registered email addresses of the uploading user.
This permission allows users to bypass parts of that validation, which
may be necessary when mirroring changes from an upstream project.</p></div>
<div class="paragraph"><p>Allows the use of the server&#8217;s own name and email on the committer
line of a new commit object.  This should only be necessary when force
pushing a commit history which has been rewritten by <em>git filter-branch</em>
and that contains merge commits previously created by this Gerrit Code
Review server.</p></div>
<h3 id="category_owner">Owner</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Owner</tt> category controls which groups can modify the project&#8217;s
configuration.  Users who are members of an owner group can:</p></div>
<div class="ulist"><ul>
<li>
<p>
Change the project description
</p>
</li>
<li>
<p>
Create/delete a branch through the web UI (not SSH)
</p>
</li>
<li>
<p>
Grant/revoke any access rights, including <tt>Owner</tt>
</p>
</li>
</ul></div>
<div class="paragraph"><p>Note that project owners implicitly have branch creation or deletion
through the web UI, but not through SSH.  To get SSH branch access
project owners must grant an access right to a group they are a
member of, just like for any other user.</p></div>
<div class="paragraph"><p>Ownership over a particular branch subspace may be delegated by
entering a branch pattern.  To delegate control over all branches
that begin with <tt>qa/</tt> to the QA group, add <tt>Owner</tt> category
for reference <tt>refs/heads/qa/\*</tt>.  Members of the QA group can
further refine access, but only for references that begin with
<tt>refs/heads/qa/</tt>. See <a href="#project_owners">project owners</a> to find
out more about this role.</p></div>
<h3 id="category_push">Push</h3><div style="clear:left"></div>
<div class="paragraph"><p>This category controls how users are allowed to upload new commits
to projects in Gerrit. It can either give permission to push
directly into a branch, bypassing any code review process
that would otherwise be used. Or it may give permission to upload
new changes for code review, this depends on which namespace the
permission is granted to.</p></div>
<h4 id="category_push_direct">Direct Push</h4>
<div class="paragraph"><p>Any existing branch can be fast-forwarded to a new commit.
Creation of new branches is controlled by the
<a href="access-control.html#category_create"><em>Create Reference</em></a>
category.  Deletion of existing branches is rejected.  This is the
safest mode as commits cannot be discarded.</p></div>
<div class="ulist"><ul>
<li>
<p>
Force option
</p>
<div class="paragraph"><p>Allows an existing branch to be deleted. Since a force push is
effectively a delete immediately followed by a create, but performed
atomically on the server and logged, this option also permits forced
push updates to branches.  Enabling this option allows existing commits
to be discarded from a project history.</p></div>
</li>
</ul></div>
<div class="paragraph"><p>The push category is primarily useful for projects that only want to
take advantage of Gerrit&#8217;s access control features and do not need
its code review functionality.  Projects that need to require code
reviews should not grant this category.</p></div>
<h4 id="category_push_review">Upload To Code Review</h4>
<div class="paragraph"><p>The <tt>Push</tt> access right granted on the namespace
<tt>refs/for/refs/heads/BRANCH</tt> permits the user to upload a non-merge
commit to the project&#8217;s <tt>refs/for/BRANCH</tt> namespace, creating a new
change for code review.</p></div>
<div class="paragraph"><p>A user must be able to clone or fetch the project in order to create
a new commit on their local system, so in practice they must also
have the <tt>Read</tt> access granted to upload a change.</p></div>
<div class="paragraph"><p>For an open source, public Gerrit installation, it is common to
grant <tt>Read</tt> and <tt>Push</tt> for <tt>refs/for/refs/heads/*</tt>
to <tt>Registered Users</tt> in the <tt>All-Projects</tt> ACL.  For more
private installations, its common to simply grant <tt>Read</tt> and
<tt>Push</tt> for <tt>refs/for/refs/heads/*</tt> to all users of a project.</p></div>
<div class="ulist"><ul>
<li>
<p>
Force option
</p>
<div class="paragraph"><p>The force option has no function when granted to a branch in the
<tt>refs/for/refs/heads/*</tt> namespace.</p></div>
</li>
</ul></div>
<h3 id="category_push_merge">Push Merge Commits</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Push Merge Commit</tt> permits the user to upload merge commits.
It&#8217;s an addon to the <a href="#category_push">Push</a> access right, and so it
won&#8217;t be sufficient with only <tt>Push Merge Commit</tt> granted for a push
to happen.  Some projects wish to restrict merges to being created by
Gerrit. By granting <tt>Push</tt> without <tt>Push Merge Commit</tt>, the only
merges that enter the system will be those created by Gerrit.</p></div>
<h3 id="category_push_annotated">Push Annotated Tag</h3><div style="clear:left"></div>
<div class="paragraph"><p>This category permits users to push an annotated tag object over
SSH into the project&#8217;s repository.  Typically this would be done
with a command line such as:</p></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="literalblock">
<div class="content">
<pre><tt>git push ssh://USER@HOST:PORT/PROJECT tag v1.0</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>Tags must be annotated (created with <tt>git tag -a</tt> or <tt>git tag -s</tt>),
should exist in the <tt>refs/tags/</tt> namespace, and should be new.</p></div>
<div class="paragraph"><p>This category is intended to be used to publish tags when a project
reaches a stable release point worth remembering in history.</p></div>
<div class="paragraph"><p>It allows for a new annotated (unsigned) tag to be created.  The
tagger email address must be verified for the current user.</p></div>
<div class="paragraph"><p>To push tags created by users other than the current user (such
as tags mirrored from an upstream project), <tt>Forge Committer Identity</tt>
must be also granted in addition to <tt>Push Annotated Tag</tt>.</p></div>
<div class="paragraph"><p>To push lightweight (non annotated) tags, grant
<a href="#category_create"><tt>Create Reference</tt></a> for reference name
<tt>refs/tags/*</tt>, as lightweight tags are implemented just like
branches in Git.</p></div>
<div class="paragraph"><p>To delete or overwrite an existing tag, grant <tt>Push</tt> with the force
option enabled for reference name <tt>refs/tags/*</tt>, as deleting a tag
requires the same permission as deleting a branch.</p></div>
<h3 id="category_read">Read</h3><div style="clear:left"></div>
<div class="paragraph"><p>The <tt>Read</tt> category controls visibility to the project&#8217;s
changes, comments, code diffs, and Git access over SSH or HTTP.
A user must have this access granted in order to see a project, its
changes, or any of its data.</p></div>
<div class="paragraph"><p>This category has a special behavior, where the per-project ACL is
evaluated before the global all projects ACL.  If the per-project
ACL has granted <tt>Read</tt> with <em>DENY</em>, and does not otherwise grant
<tt>Read</tt> with <em>ALLOW</em>, then a <tt>Read</tt> in the all projects ACL
is ignored.  This behavior is useful to hide a handful of projects
on an otherwise public server.</p></div>
<div class="paragraph"><p>For an open source, public Gerrit installation it is common to grant
<tt>Read</tt> to <tt>Anonymous Users</tt> in the <tt>All-Projects</tt> ACL, enabling
casual browsing of any project&#8217;s changes, as well as fetching any
project&#8217;s repository over SSH or HTTP.  New projects can be
temporarily hidden from public view by granting <tt>Read</tt> with <em>DENY</em>
to <tt>Anonymous Users</tt> and granting <tt>Read</tt> to the project owner&#8217;s
group within the per-project ACL.</p></div>
<div class="paragraph"><p>For a private Gerrit installation using a trusted HTTP authentication
source, granting <tt>Read</tt> to <tt>Registered Users</tt> may be more
typical, enabling read access only to those users who have been
able to authenticate through the HTTP access controls.  This may
be suitable in a corporate deployment if the HTTP access control
is already restricted to the correct set of users.</p></div>
<h3 id="category_submit">Submit</h3><div style="clear:left"></div>
<div class="paragraph"><p>This category permits users to push the <tt>Submit Patch Set n</tt> button
on the web UI.</p></div>
<div class="paragraph"><p>Submitting a change causes it to be merged into the destination
branch as soon as possible, making it a permanent part of the
project&#8217;s history.</p></div>
<div class="paragraph"><p>In order to submit, all approval categories (such as <tt>Verified</tt> and
<tt>Code Review</tt>, above) must enable submit, and also must not block it.
See above for details on each category.</p></div>
<h3 id="category_makeoneup">Your Category Here</h3><div style="clear:left"></div>
<div class="paragraph"><p>Gerrit administrators can also make up their own categories.</p></div>
<div class="paragraph"><p>See above for descriptions of how <a href="#category_verified"><tt>Verified</tt></a>
and <a href="#category_review"><tt>Code Review</tt></a> work, and insert your own
category with <tt>function_name = 'MaxWithBlock'</tt> to get the same
behavior over your own range of values, in any category you desire.</p></div>
<div class="paragraph"><p>Ensure <tt>category_id</tt> is unique within your <tt>approval_categories</tt>
table.  The default values <tt>VRIF</tt> and <tt>CVRF</tt> used for the categories
described above are simply that, defaults, and have no special
meaning to Gerrit.</p></div>
<div class="paragraph"><p>The <tt>position</tt> column of <tt>approval_categories</tt> controls which column
of the <em>Approvals</em> table the category appears in, providing some
layout control to the administrator.</p></div>
<div class="paragraph"><p>All <tt>MaxWithBlock</tt> categories must have at least one positive value
in the <tt>approval_category_values</tt> table, or else submit will never
be enabled.</p></div>
<div class="paragraph"><p>To permit blocking submits, ensure a negative value is defined for
your new category.  If you do not wish to have a blocking submit
level for your category, do not define values less than 0.</p></div>
<div class="paragraph"><p>Keep in mind that category definitions are currently global to
the entire Gerrit instance, and affect all projects hosted on it.
Any change to a category definition affects everyone.</p></div>
<div class="paragraph"><p>For example, to define a new 3-valued category that behaves exactly
like <tt>Verified</tt>, but has different names/labels:</p></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="literalblock">
<div class="content">
<pre><tt>INSERT INTO approval_categories
  (name
  ,position
  ,function_name
  ,category_id)
VALUES
  ('Copyright Check'
  ,3
  ,'MaxWithBlock'
  ,'copy');</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>INSERT INTO approval_category_values
  (category_id,value,name)
VALUES
  ('copy', -1, 'Do not have copyright');</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>INSERT INTO approval_category_values
  (category_id,value,name)
VALUES
  ('copy', 0, 'No score');</tt></pre>
</div></div>
<div class="literalblock">
<div class="content">
<pre><tt>INSERT INTO approval_category_values
  (category_id,value,name)
VALUES
  ('copy', 1, 'Copyright clear');</tt></pre>
</div></div>
</div></div>
<div class="paragraph"><p>The new column will appear at the end of the table (in position 3),
and <tt>-1 Do not have copyright</tt> will block submit, while <tt>+1 Copyright
clear</tt> is required to enable submit.</p></div>
<div class="admonitionblock" id="restart_changes">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Restart the Gerrit web application and reload all browsers after
making any database changes to approval categories.  Browsers are
sent the list of known categories when they first visit the site,
and don&#8217;t notice changes until the page is closed and opened again,
or is reloaded.</td>
</tr></table>
</div>
</div>
<h2 id="_examples_of_typical_roles_in_a_project">Examples of typical roles in a project</h2>
<div class="sectionbody">
<div class="paragraph"><p>Below follows a set of typical roles on a server and which access
rights these roles typically should be granted. You may see them as
general guide lines for a typical way to set up your project on a
brand new Gerrit instance.</p></div>
<h3 id="examples_contributor">Contributor</h3><div style="clear:left"></div>
<div class="paragraph"><p>This is the typical user on a public server. They are able to read
your project and upload new changes to it. They are able to give
feedback on other changes as well, but are unable to block or approve
any changes.</p></div>
<div class="paragraph"><p>Suggested access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#category_read"><tt>Read</tt></a> on <em>refs/heads/*</em> and <em>refs/tags/*</em>
</p>
</li>
<li>
<p>
<a href="#category_push"><tt>Push</tt></a> to <em>refs/for/refs/heads/*</em> and <em>refs/changes/*</em>
</p>
</li>
<li>
<p>
<a href="#category_label-Code-Review"><tt>Code review</tt></a> with range <em>-1</em> to <em>+1</em>
</p>
</li>
</ul></div>
<h3 id="examples_developer">Developer</h3><div style="clear:left"></div>
<div class="paragraph"><p>This is the typical core developer on a public server.  They are able
to read the project, upload changes to a branch.  They are allowed to
push merge commits to merge branches together.  Also, they are allowed
to forge author identity, thus handling commits belonging to others
than themselves, effectively allowing them to transfer commits
between different branches.</p></div>
<div class="paragraph"><p>They are furthermore able to code review and verify commits, and
eventually submit them.  If you have an automated CI system that
builds all uploaded patch sets you might want to skip the
verification rights for the developer and let the CI system do that
exclusively.</p></div>
<div class="paragraph"><p>Suggested access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#category_read"><tt>Read</tt></a> on <em>refs/heads/*</em> and <em>refs/tags/*</em>
</p>
</li>
<li>
<p>
<a href="#category_push"><tt>Push</tt></a> to <em>refs/for/refs/heads/*</em> and <em>refs/changes/*</em>
</p>
</li>
<li>
<p>
<a href="#category_push_merge"><tt>Push merge commit</tt></a> to <em>refs/for/refs/heads/*</em> and <em>refs/changes/*</em>
</p>
</li>
<li>
<p>
<a href="#category_forge_author"><tt>Forge Author Identity</tt></a>
</p>
</li>
<li>
<p>
<a href="#category_label-Code-Review"><tt>Label: Code review</tt></a> with range <em>-2</em> to <em>+2</em>
</p>
</li>
<li>
<p>
<a href="#category_label-Verified"><tt>Label: Verify</tt></a> with range <em>-1</em> to <em>+1</em>
</p>
</li>
<li>
<p>
<a href="#category_submit"><tt>Submit</tt></a>
</p>
</li>
</ul></div>
<div class="paragraph"><p>If the project is small or the developers are seasoned it might make
sense to give them the freedom to push commits directly to a branch.</p></div>
<div class="paragraph"><p>Optional access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#category_push"><tt>Push</tt></a> to <em>refs/heads/*</em>
</p>
</li>
<li>
<p>
<a href="#category_push_merge"><tt>Push merge commit</tt></a> to <em>refs/heads/*</em>
</p>
</li>
</ul></div>
<h3 id="examples_cisystem">CI system</h3><div style="clear:left"></div>
<div class="paragraph"><p>A typical Continous Integration system should be able to download new changes
to build and then leave a verdict somehow.</p></div>
<div class="paragraph"><p>As an example, the popular
<a href="https://wiki.jenkins-ci.org/display/JENKINS/Gerrit+Trigger">gerrit-trigger plugin</a>
for Jenkins/Hudson can set labels at:</p></div>
<div class="ulist"><ul>
<li>
<p>
The start of a build
</p>
</li>
<li>
<p>
A successful build
</p>
</li>
<li>
<p>
An unstable build (tests fails)
</p>
</li>
<li>
<p>
A failed build
</p>
</li>
</ul></div>
<div class="paragraph"><p>Usually the range chosen for this verdict is the verify label.  Depending on
the size of your project and discipline of involved developers you might want
to limit access right to the +1 <tt>Verify</tt> label to the CI system only.  That
way it&#8217;s guaranteed that submitted commits always get built and pass tests
successfully.</p></div>
<div class="paragraph"><p>If the build doesn&#8217;t complete successfully the CI system can set the
<tt>Verify</tt> label to -1.  However that means that a failed build will block
submit of the change even if someone else sets <tt>Verify</tt> +1.  Depending on the
project and how much the CI system can be trusted for accurate results, a
blocking label might not be feasible.  A recommended alternative is to set the
label <tt>Code-review</tt> to -1 instead, as it isn&#8217;t a blocking label but still
shows a red label in the Gerrit UI.  Optionally; to enable the possibility to
deliver different results (build error vs unstable for instance) it&#8217;s also
possible to set <tt>Code-review</tt> +1 as well.</p></div>
<div class="paragraph"><p>If pushing new changes is granted, it&#8217;s possible to automate cherry-pick of
submitted changes for upload to other branches under certain conditions.  This
is probably not the first step of what a project wants to automate however,
and so the push right can be found under the optional section.</p></div>
<div class="paragraph"><p>Suggested access rights to grant, that won&#8217;t block changes:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#category_read"><tt>Read</tt></a> on <em>refs/heads/*</em> and <em>refs/tags/*</em>
</p>
</li>
<li>
<p>
<a href="#category_label-Code-Review"><tt>Label: Code review</tt></a> with range <em>-1</em> to <em>0</em>
</p>
</li>
<li>
<p>
<a href="#category_label-Verified"><tt>Label: Verify</tt></a> with range <em>0</em> to <em>+1</em>
</p>
</li>
</ul></div>
<div class="paragraph"><p>Optional access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#category_label-Code-Review"><tt>Label: Code review</tt></a> with range <em>-1</em> to <em>+1</em>
</p>
</li>
<li>
<p>
<a href="#category_push"><tt>Push</tt></a> to <em>refs/for/refs/heads/*</em> and <em>refs/changes/*</em>
</p>
</li>
</ul></div>
<h3 id="examples_integrator">Integrator</h3><div style="clear:left"></div>
<div class="paragraph"><p>Integrators are like developers but with some additional rights granted due
to their administrative role in a project.  They can upload or push any commit
with any committer email (not just their own) and they can also create new
tags and branches.</p></div>
<div class="paragraph"><p>Suggested access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#examples_developer">Developer rights</a>
</p>
</li>
<li>
<p>
<a href="#category_push"><tt>Push</tt></a> to <em>refs/heads/*</em>
</p>
</li>
<li>
<p>
<a href="#category_push_merge"><tt>Push merge commit</tt></a> to <em>refs/heads/*</em>
</p>
</li>
<li>
<p>
<a href="#category_forge_committer"><tt>Forge Committer Identity</tt></a> to <em>refs/for/refs/heads/*</em> and <em>refs/changes/*</em>
</p>
</li>
<li>
<p>
<a href="#category_create"><tt>Create Reference</tt></a> to <em>refs/heads/*</em>
</p>
</li>
<li>
<p>
<a href="#category_push_annotated"><tt>Push Annotated Tag</tt></a> to <em>refs/tags/*</em>
</p>
</li>
</ul></div>
<h3 id="examples_project-owner">Project owner</h3><div style="clear:left"></div>
<div class="paragraph"><p>The project owner is almost like an integrator but with additional destructive
power in the form of being able to delete branches.  Optionally these users
also have the power to configure access rights in gits assigned to them.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">These users should be really knowledgable about git, for instance knowing why
tags never should be removed from a server.  This role is granted potentially
destructive access rights and cleaning up after such a mishap could be time
consuming!</td>
</tr></table>
</div>
<div class="paragraph"><p>Suggested access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#examples_integrator">Integrator rights</a>
</p>
</li>
<li>
<p>
<a href="#category_push"><tt>Push</tt></a> with the force option to <em>refs/heads/*</em> and <em>refs/tags/*</em>
</p>
</li>
</ul></div>
<div class="paragraph"><p>Optional access right to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#category_owner"><tt>Owner</tt></a> in the gits they mostly work with.
</p>
</li>
</ul></div>
<h3 id="examples_administrator">Administrator</h3><div style="clear:left"></div>
<div class="paragraph"><p>The administrator role is the most powerful role known in the Gerrit universe.
This role may grant itself (or others) any access right, and it already has
all capabilities granted as well.  By default the
<a href="#administrators"><tt>Administrators</tt> group</a> is the group that has this role.</p></div>
<div class="paragraph"><p>Mandatory access rights:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#capability_administrateServer">The <tt>Administrate Server</tt> capability</a>
</p>
</li>
</ul></div>
<div class="paragraph"><p>Suggested access rights to grant:</p></div>
<div class="ulist"><ul>
<li>
<p>
<a href="#examples_project-owner">Project owner rights</a>
</p>
</li>
</ul></div>
</div>
<h2 id="conversion_table">Conversion table from 2.1.x series to 2.2.x series</h2>
<div class="sectionbody">
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left" valign="top">Gerrit 2.1.x                 </th>
<th align="left" valign="top">Gerrit 2.2.x</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Code review</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_label-Code-Review">Label: Code review</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Verify</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_label-Verified">Label: Verify</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Forge Identity +1</p></td>
<td align="left" valign="top"><p class="table">Forge <a href="#category_forge_author">author</a> identity</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Forge Identity +2</p></td>
<td align="left" valign="top"><p class="table">Forge <a href="#category_forge_committer">committer</a> &amp; <a href="#category_forge_author">author</a> identity</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Forge Identity +3</p></td>
<td align="left" valign="top"><p class="table">Forge <a href="#category_forge_server">server</a> &amp; <a href="#category_forge_committer">committer</a> &amp; <a href="#category_forge_author">author</a> identity</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Owner</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_owner">Owner</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push branch +1</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_push_direct">Push</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push branch +2</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_create">Create reference</a> &amp; <a href="#category_push_direct">Push</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push branch +3</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_push_direct">Push</a> (with force) &amp; <a href="#category_create">Create reference</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push tag +1 &amp; Push Branch +2</p></td>
<td align="left" valign="top"><p class="table">No support to limit to push signed tag</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push tag +2 &amp; Push Branch +2</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_push_annotated">Push annotated tag</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push Branch +2 (refs/tags/*)</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_create">Create reference</a> (refs/tags/&#8230;)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Push Branch +3 (refs/tags/*)</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_push_direct">Push</a> (with force on refs/tags/&#8230;)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Read +1</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_read">Read</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Read +2</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_read">Read</a> &amp; <a href="#category_push_review">Push</a> (refs/for/refs/&#8230;)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Read +3</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_read">Read</a> &amp; <a href="#category_push_review">Push</a> (refs/for/refs/&#8230;) &amp; <a href="#category_push_merge">Push Merge Commit</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Submit</p></td>
<td align="left" valign="top"><p class="table"><a href="#category_submit">Submit</a></p></td>
</tr>
</tbody>
</table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">In Gerrit 2.2.x, the way to set permissions for upload has changed entirely.
To upload a change for review is no longer a separate permission type,
instead you grant ordinary push permissions to the actual
recieving reference. In practice this means that you set push permissions
on <tt>refs/for/refs/heads/&lt;branch&gt;</tt> rather than permissions to upload changes
on <tt>refs/heads/&lt;branch&gt;</tt>.</td>
</tr></table>
</div>
</div>
<h2 id="_system_capabilities">System capabilities</h2>
<div class="sectionbody">
<div class="paragraph"><p>The system capabilities control actions that the administrators of
the server can perform which usually affect the entire
server in some way.  The administrators may delegate these
capabilities to trusted groups of users.</p></div>
<div class="paragraph"><p>Delegation of capabilities allows groups to be granted a subset of
administrative capabilities without being given complete
administrative control of the server.  This makes it possible to
keep fewer users in the administrators group, even while spreading
much of the server administration burden out to more users.</p></div>
<div class="paragraph"><p>Below you find a list of capabilities available:</p></div>
<h3 id="capability_administrateServer">Administrate Server</h3><div style="clear:left"></div>
<div class="paragraph"><p>This is in effect the owner and administrator role of the Gerrit
instance.  Any members of a group granted this capability will be
able to grant any access right to any group. They will also have all
capabilities granted to them automatically.</p></div>
<h3 id="capability_createAccount">Create Account</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow <a href="cmd-create-account.html">account creation over the ssh prompt</a>.
This capability allows the granted group members to create non-interactive
service accounts.  These service accounts are generally used for automation
and made to be members of the
<a href="access-control.html#non-interactive_users"><em>Non-Interactive users</em></a> group.</p></div>
<h3 id="capability_createGroup">Create Group</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow group creation.  Groups are used to grant users access to different
actions in projects.  This capability allows the granted group members to
either <a href="cmd-create-group.html">create new groups via ssh</a> or via the web UI.</p></div>
<h3 id="capability_createProject">Create Project</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow project creation.  This capability allows the granted group to
either <a href="cmd-create-project.html">create new git projects via ssh</a>
or via the web UI.</p></div>
<h3 id="capability_flushCaches">Flush Caches</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow the flushing of Gerrit&#8217;s caches.  This capability allows the granted
group to <a href="cmd-flush-caches.html">flush some or all Gerrit caches via ssh</a>.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">This capability doesn&#8217;t imply permissions to the show-caches command.  For that
you need the <a href="#capability_viewCaches">view caches capability</a>.</td>
</tr></table>
</div>
<h3 id="capability_kill">Kill Task</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow the operation of the <a href="cmd-kill.html">kill command over ssh</a>.  The
kill command ends tasks that currently occupy the Gerrit server, usually
a replication task or a user initiated task such as an upload-pack or
recieve-pack.</p></div>
<h3 id="capability_priority">Priority</h3><div style="clear:left"></div>
<div class="paragraph"><p>This capability allows users to use
<a href="config-gerrit.html#sshd.batchThreads">the thread pool reserved</a> for
<a href="access-control.html#non-interactive_users"><em>Non-Interactive Users</em></a>.
It&#8217;s a binary value in that granted users either have access to the thread
pool, or they don&#8217;t.</p></div>
<div class="paragraph"><p>There are three modes for this capability and they&#8217;re listed by rising
priority:</p></div>
<div class="dlist"><dl>
<dt class="hdlist1">
No capability configured.
</dt>
<dd>
<p>
The user isn&#8217;t a member of a group with any priority capability granted. By
default the user is then in the <em>INTERACTIVE</em> thread pool.
</p>
</dd>
<dt class="hdlist1">
<em>BATCH</em>
</dt>
<dd>
<p>
If there&#8217;s a thread pool configured for <em>Non-Interactive Users</em> and a user is
granted the priority capability with the <em>BATCH</em> mode selected, the user ends
up in the separate batch user thread pool. This is true unless the user is
also granted the below <em>INTERACTIVE</em> option.
</p>
</dd>
<dt class="hdlist1">
<em>INTERACTIVE</em>
</dt>
<dd>
<p>
If a user is granted the priority capability with the <em>INTERACTIVE</em> option,
regardless if they also have the <em>BATCH</em> option or not, they are in the
<em>INTERACTIVE</em> thread pool.
</p>
</dd>
</dl></div>
<h3 id="capability_queryLimit">Query Limit</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow site administrators to configure the query limit for users to
be above the default hard-coded value of 500.  Administrators can add
a global block to <tt>All-Projects</tt> with group(s) that
should have different limits:</p></div>
<div class="paragraph"><p>When applying a query limit to a user the largest value granted by
any of their groups is used.</p></div>
<div class="paragraph"><p>This limit applies not only to the <a href="cmd-query.html"><tt>gerrit query</tt></a>
command, but also to the web UI results pagination size.</p></div>
<h3 id="capability_startReplication">Start Replication</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow access to execute <a href="cmd-replicate.html">the <tt>gerrit replicate</tt> command</a>.</p></div>
<h3 id="capability_viewCaches">View Caches</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow querying for status of Gerrit&#8217;s internal caches.  This capability allows
the granted group to
<a href="cmd-show-caches.html">look at some or all Gerrit caches via ssh</a>.</p></div>
<h3 id="capability_viewConnections">View Connections</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow querying for status of Gerrit&#8217;s current client connections.  This
capability allows the granted group to
<a href="cmd-show-connections.html">look at Gerrit&#8217;s current connections via ssh</a>.</p></div>
<h3 id="capability_viewQueue">View Queue</h3><div style="clear:left"></div>
<div class="paragraph"><p>Allow querying for status of Gerrit&#8217;s internal task queue.  This capability
allows the granted group to
<a href="cmd-show-queue.html">look at the Gerrit task queue via ssh</a>.</p></div>
</div>
<hr style="
  height: 2px;
  color: silver;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
">
<div class="paragraph"><p>Part of <a href="index.html">Gerrit Code Review</a></p></div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Version 2.3<br />
Last updated 2012-04-10 14:44:28 MDT
</div>
</div>
</body>
</html>
